<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Configuring and building the library</title>
<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="Chapter 1. Boost.Log v2">
<link rel="up" href="../installation.html" title="Installation and compatibility">
<link rel="prev" href="../installation.html" title="Installation and compatibility">
<link rel="next" href="../design.html" title="Design overview">
<meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td></tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../installation.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../installation.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../design.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="log.installation.config"></a><a class="link" href="config.html" title="Configuring and building the library">Configuring and building the
      library</a>
</h3></div></div></div>
<p>
        The library has a separately compiled part which should be built as described
        in the <a href="https://www.boost.org/doc/libs/release/more/getting_started/" target="_top">Getting
        Started guide</a>. One thing should be noted, though. If your application
        consists of more than one module (e.g. an exe and one or several dll's) that
        use Boost.Log, the library <span class="underline">must</span> be
        built as a shared object. If you have a single executable or a single module
        that works with Boost.Log, you may build the library as a static library.
      </p>
<p>
        The library supports a number of configuration macros:
      </p>
<div class="table">
<a name="log.installation.config.configuration_macros"></a><p class="title"><b>Table 1.1. Configuration macros</b></p>
<div class="table-contents"><table class="table" summary="Configuration macros">
<colgroup>
<col>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                <p>
                  Macro name
                </p>
              </th>
<th>
                <p>
                  Effect
                </p>
              </th>
<th>
                <p>
                  CMake notes
                </p>
              </th>
</tr></thead>
<tbody>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">BOOST_LOG_DYN_LINK</span></code>
                </p>
              </td>
<td>
                <p>
                  If defined in user code, the library will assume the binary is
                  built as a dynamically loaded library ("dll" or "so").
                  Otherwise it is assumed that the library is built in static mode.
                  This macro must be either defined or not defined for all translation
                  units of user application that uses logging. This macro can help
                  with auto-linking on platforms that support it.
                </p>
              </td>
<td>
                <p>
                  Defined automatically depending on <code class="computeroutput"><span class="identifier">BUILD_SHARED_LIBS</span></code>
                  CMake option.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">BOOST_ALL_DYN_LINK</span></code>
                </p>
              </td>
<td>
                <p>
                  Same as <code class="computeroutput"><span class="identifier">BOOST_LOG_DYN_LINK</span></code>
                  but also affects other Boost libraries the same way.
                </p>
              </td>
<td>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">BOOST_USE_WINAPI_VERSION</span></code>
                </p>
              </td>
<td>
                <p>
                  Affects compilation of both the library and user's code. This macro
                  is Windows-specific. Selects the target Windows version for various
                  Boost libraries, including Boost.Log. Code compiled for a particular
                  Windows version will likely fail to run on the older Windows versions,
                  but may improve performance because of using newer OS features.
                  The macro is expected to have an integer value equivalent to <a href="https://msdn.microsoft.com/en-us/library/6sehtctf.aspx" target="_top"><code class="computeroutput"><span class="identifier">_WIN32_WINNT</span></code></a>.
                </p>
              </td>
<td>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">BOOST_LOG_NO_THREADS</span></code>
                </p>
              </td>
<td>
                <p>
                  If defined, disables multithreading support. Affects the compilation
                  of both the library and users' code. The macro is automatically
                  defined if no threading support is detected.
                </p>
              </td>
<td>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">BOOST_LOG_WITHOUT_CHAR</span></code>
                </p>
              </td>
<td>
                <p>
                  If defined, disables support for narrow character logging. Affects
                  the compilation of both the library and users' code.
                </p>
              </td>
<td>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">BOOST_LOG_WITHOUT_WCHAR_T</span></code>
                </p>
              </td>
<td>
                <p>
                  If defined, disables support for wide character logging. Affects
                  the compilation of both the library and users' code.
                </p>
              </td>
<td>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">BOOST_LOG_NO_QUERY_PERFORMANCE_COUNTER</span></code>
                </p>
              </td>
<td>
                <p>
                  This macro is only useful on Windows. It affects the compilation
                  of both the library and users' code. If defined, disables support
                  for the <code class="computeroutput"><span class="identifier">QueryPerformanceCounter</span></code>
                  API in the <code class="computeroutput"><span class="identifier">timer</span></code>
                  attribute. This will result in significantly less accurate time
                  readings. The macro is intended to solve possible problems with
                  earlier revisions of AMD Athlon CPU, described <a href="http://support.microsoft.com/?scid=kb%3ben-us%3b895980" target="_top">here</a>
                  and <a href="http://support.microsoft.com/?id=896256" target="_top">here</a>.
                  There are also known chipset hardware failures that may prevent
                  this API from functioning properly (see <a href="http://support.microsoft.com/kb/274323" target="_top">here</a>).
                </p>
              </td>
<td>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">BOOST_LOG_USE_NATIVE_SYSLOG</span></code>
                </p>
              </td>
<td>
                <p>
                  Affects only compilation of the library. If for some reason support
                  for the native SysLog API is not detected automatically, define
                  this macro to forcibly enable it.
                </p>
              </td>
<td>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">BOOST_LOG_WITHOUT_DEFAULT_FACTORIES</span></code>
                </p>
              </td>
<td>
                <p>
                  Affects only compilation of the library. If defined, the parsers
                  for settings will be built without any default factories for filters
                  and formatters. The user will have to register all attributes in
                  the library before parsing any filters or formatters from strings.
                  This can substantially reduce the binary size.
                </p>
              </td>
<td>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">BOOST_LOG_WITHOUT_SETTINGS_PARSERS</span></code>
                </p>
              </td>
<td>
                <p>
                  Affects only compilation of the library. If defined, none of the
                  facilities related to the parsers for settings will be built. This
                  can substantially reduce the binary size.
                </p>
              </td>
<td>
                <p>
                  Disables compilation of the <code class="computeroutput"><span class="identifier">boost_log_setup</span></code>
                  library.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">BOOST_LOG_WITHOUT_DEBUG_OUTPUT</span></code>
                </p>
              </td>
<td>
                <p>
                  Affects only compilation of the library. If defined, the support
                  for debugger output on Windows will not be built.
                </p>
              </td>
<td>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">BOOST_LOG_WITHOUT_EVENT_LOG</span></code>
                </p>
              </td>
<td>
                <p>
                  Affects only compilation of the library. If defined, the support
                  for Windows event log will not be built. Defining the macro also
                  makes Message Compiler toolset unnecessary.
                </p>
              </td>
<td>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">BOOST_LOG_WITHOUT_SYSLOG</span></code>
                </p>
              </td>
<td>
                <p>
                  Affects only compilation of the library. If defined, the support
                  for syslog backend will not be built.
                </p>
              </td>
<td>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">BOOST_LOG_WITHOUT_IPC</span></code>
                </p>
              </td>
<td>
                <p>
                  Affects only compilation of the library. If defined, the support
                  for interprocess queues will not be built.
                </p>
              </td>
<td>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">BOOST_LOG_NO_SHORTHAND_NAMES</span></code>
                </p>
              </td>
<td>
                <p>
                  Affects only compilation of users' code. If defined, some deprecated
                  shorthand macro names will not be available.
                </p>
              </td>
<td>
                <p>
                  Not a CMake configuration option.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">BOOST_LOG_USE_COMPILER_TLS</span></code>
                </p>
              </td>
<td>
                <p>
                  Affects only compilation of the library. This macro enables support
                  for compiler intrinsics for thread-local storage. Defining it may
                  improve performance of Boost.Log if certain usage limitations are
                  acceptable. See below for more comments.
                </p>
              </td>
<td>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">BOOST_LOG_USE_STD_REGEX</span></code>,
                  <code class="computeroutput"><span class="identifier">BOOST_LOG_USE_BOOST_REGEX</span></code>
                  or <code class="computeroutput"><span class="identifier">BOOST_LOG_USE_BOOST_XPRESSIVE</span></code>
                </p>
              </td>
<td>
                <p>
                  Affects only compilation of the library. By defining one of these
                  macros the user can instruct Boost.Log to use <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">regex</span></code>,
                  <a href="https://www.boost.org/doc/libs/release/libs/regex/doc/html/index.html" target="_top">Boost.Regex</a>
                  or <a href="https://www.boost.org/doc/libs/release/doc/html/xpressive.html" target="_top">Boost.Xpressive</a>
                  internally for string matching filters parsed from strings and
                  settings. If none of these macros is defined then Boost.Log uses
                  <a href="https://www.boost.org/doc/libs/release/libs/regex/doc/html/index.html" target="_top">Boost.Regex</a>
                  by default. Using <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">regex</span></code>
                  or <a href="https://www.boost.org/doc/libs/release/libs/regex/doc/html/index.html" target="_top">Boost.Regex</a>
                  typically produces smaller executables, <a href="https://www.boost.org/doc/libs/release/libs/regex/doc/html/index.html" target="_top">Boost.Regex</a>
                  usually also being the fastest in run time. Using <a href="https://www.boost.org/doc/libs/release/doc/html/xpressive.html" target="_top">Boost.Xpressive</a>
                  allows to eliminate the dependency on <a href="https://www.boost.org/doc/libs/release/libs/regex/doc/html/index.html" target="_top">Boost.Regex</a>
                  compiled binary. Note that these macros do not affect <a class="link" href="../detailed/expressions.html#log.detailed.expressions.predicates.advanced_string_matching" title="Advanced string matching filter">filtering
                  expressions</a> created by users.
                </p>
              </td>
<td>
                <p>
                  Instead of definitng one of these macros, use <code class="computeroutput"><span class="identifier">BOOST_LOG_USE_REGEX_BACKEND</span></code>
                  string option with one of the following values: "std::regex",
                  "Boost.Regex" or "Boost.Xpressive". The macros
                  will be defined accordingly by CMake.
                </p>
              </td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break"><p>
        You can define configuration macros in the <code class="computeroutput"><span class="identifier">b2</span></code>
        command line, like this:
      </p>
<pre class="programlisting">b2 --with-log variant=release define=BOOST_LOG_WITHOUT_EVENT_LOG define=BOOST_USE_WINAPI_VERSION=0x0600 stage
</pre>
<p>
        With CMake, the configuration macros can be specified as CMake options in
        the command line like this:
      </p>
<pre class="programlisting">cmake .. -DCMAKE_BUILD_TYPE=Release -DBOOST_LOG_WITHOUT_EVENT_LOG=On
</pre>
<p>
        However, it may be more convenient to define configuration macros in the
        "boost/config/user.hpp" file in order to automatically define them
        both for the library and user's projects. If none of the options are specified,
        the library will try to support the most comprehensive setup, including support
        for all character types and features available for the target platform.
      </p>
<p>
        The logging library uses several other Boost libraries that require building
        too. These are <a href="https://www.boost.org/doc/libs/release/libs/filesystem/doc/index.htm" target="_top">Boost.Filesystem</a>,
        <a href="https://www.boost.org/doc/libs/release/libs/system/doc/html/system.html" target="_top">Boost.System</a>,
        <a href="https://www.boost.org/doc/libs/release/doc/html/date_time.html" target="_top">Boost.DateTime</a>,
        <a href="https://www.boost.org/doc/libs/release/doc/html/thread.html" target="_top">Boost.Thread</a>
        and in some configurations <a href="https://www.boost.org/doc/libs/release/libs/regex/doc/html/index.html" target="_top">Boost.Regex</a>.
        Refer to their documentation for detailed instructions on the building procedure.
      </p>
<p>
        One final thing should be added. The library requires run-time type information
        (RTTI) to be enabled for both the library compilation and user's code compilation.
        Normally, this won't need anything from you except to verify that RTTI support
        is not disabled in your project.
      </p>
<h5>
<a name="log.installation.config.h0"></a>
        <span class="phrase"><a name="log.installation.config.notes_about_compiler_supplied_intrinsics_for_tls"></a></span><a class="link" href="config.html#log.installation.config.notes_about_compiler_supplied_intrinsics_for_tls">Notes
        about compiler-supplied intrinsics for TLS</a>
      </h5>
<p>
        Many widely used compilers support builtin intrinsics for managing thread-local
        storage, which is used in several parts of the library. This feature is also
        included in the C++11 standard. Generally, these intrinsics allow for a much
        more efficient access to the storage than any surrogate implementation, be
        that <a href="https://www.boost.org/doc/libs/release/doc/html/thread.html" target="_top">Boost.Thread</a>
        or even native operating system API. However, this feature has several caveats:
      </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
            Some operating systems don't support the use of these intrinsics in case
            if the TLS is defined in a shared library that is dynamically loaded
            during the application run time. These systems include Linux and Windows
            prior to Vista. Windows Vista and later do not have this issue.
          </li>
<li class="listitem">
            The TLS may not be reliably accessed from global constructors and destructors.
            At least MSVC 8.0 on Windows is known to have this problem.
          </li>
</ul></div>
<p>
        The library provides the <code class="computeroutput"><span class="identifier">BOOST_LOG_USE_COMPILER_TLS</span></code>
        configuration macro that allows to enable the use of this feature, which
        will improve the library performance at the cost of these limitations:
      </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
            The application executable must be linked with the Boost.Log library.
            It should not be loaded dynamically during run time.
          </li>
<li class="listitem">
            The application must not use logging in global constructors or destructors.
          </li>
</ul></div>
<p>
        Note that the <code class="computeroutput"><span class="identifier">BOOST_LOG_USE_COMPILER_TLS</span></code>
        macro only controls use of TLS in Boost.Log but not in other libraries used
        by Boost.Log. For example, <a href="https://www.boost.org/doc/libs/release/doc/html/boost_asio.html" target="_top">Boost.ASIO</a>
        uses compiler-supplied TLS by default. In order to build Boost.Log binaries
        completely free from use of compiler-supplied TLS, this feature has to be
        disabled in those other libraries as well (in case of <a href="https://www.boost.org/doc/libs/release/doc/html/boost_asio.html" target="_top">Boost.ASIO</a>
        this can be achieved by defining <code class="computeroutput"><span class="identifier">BOOST_ASIO_DISABLE_THREAD_KEYWORD_EXTENSION</span></code>
        when building and using Boost).
      </p>
<p>
        Also note that enabling builtin compiler support for TLS does not remove
        the dependency on <a href="https://www.boost.org/doc/libs/release/doc/html/thread.html" target="_top">Boost.Thread</a>
        or lower level OS threading primitives, including those implementing TLS.
        The purpose of using compiler intrinsics for TLS is better performance rather
        than reducing dependencies.
      </p>
<h5>
<a name="log.installation.config.h1"></a>
        <span class="phrase"><a name="log.installation.config.notes_about_native__code__phrase_role__keyword__wchar_t__phrase___code__support"></a></span><a class="link" href="config.html#log.installation.config.notes_about_native__code__phrase_role__keyword__wchar_t__phrase___code__support">Notes
        about native <code class="computeroutput"><span class="keyword">wchar_t</span></code> support</a>
      </h5>
<p>
        Some compilers, most notably MSVC, have an option to disable the native
        <code class="computeroutput"><span class="keyword">wchar_t</span></code> type, emulating it with
        a typedef for one of the standard integral types. From the C++ language perspective
        this behavior is not conforming but it may be useful for compatibility with
        some legacy code which is difficult to update.
      </p>
<p>
        By default, Boost (and Boost.Log being part of it) is built with native
        <code class="computeroutput"><span class="keyword">wchar_t</span></code> enabled. At the time
        of this writing, user will have to modify Boost.Build to enable the emulation
        mode. It is possible to build Boost.Log in this mode, but there are several
        caveats that have to be kept in mind:
      </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
            The compiled Boost.Log binaries will be exporting symbols corresponding
            to the configuration chosen at build time. The user's code will have
            to use the same setting as was used when building Boost.Log, otherwise
            linking errors will appear.
          </li>
<li class="listitem">
            Since in emulation mode <code class="computeroutput"><span class="keyword">wchar_t</span></code>
            is undistinguishable from one of the integer types, certain parts of
            the library may behave differently from the normal mode with native
            <code class="computeroutput"><span class="keyword">wchar_t</span></code>. In particular,
            wide-character literals may be rejected or formatted differently.
          </li>
<li class="listitem">
            The emulation mode is not tested, so unexpected breakages are possible.
          </li>
</ul></div>
<p>
        Because of that using the emulation mode is discouraged and should be avoided.
        In future releases of the library its support may be removed completely.
      </p>
<h5>
<a name="log.installation.config.h2"></a>
        <span class="phrase"><a name="log.installation.config.notes_for_cmake_users_on_windows"></a></span><a class="link" href="config.html#log.installation.config.notes_for_cmake_users_on_windows">Notes
        for CMake users on Windows</a>
      </h5>
<p>
        In order to compile Boost.Log with event log support on Windows using CMake,
        the initial CMake configuration should be performed with resource (<code class="computeroutput"><span class="identifier">rc</span><span class="special">.</span><span class="identifier">exe</span></code>
        or <code class="computeroutput"><span class="identifier">windres</span><span class="special">.</span><span class="identifier">exe</span></code>) and message compiler tools (<code class="computeroutput"><span class="identifier">mc</span><span class="special">.</span><span class="identifier">exe</span></code>
        or <code class="computeroutput"><span class="identifier">windmc</span><span class="special">.</span><span class="identifier">exe</span></code>) available in <code class="computeroutput"><span class="identifier">PATH</span></code>
        environment variable. With MSVC, it is recommended to run CMake in the Visual
        Studio command line or otherwise ensure that Windows SDK environment variables
        are set.
      </p>
<p>
        Alternatively, users may set <code class="computeroutput"><span class="identifier">RC</span></code>
        and <code class="computeroutput"><span class="identifier">MC</span></code> environment variables
        to paths of the resource and message compiler executables, respectively,
        or set <code class="computeroutput"><span class="identifier">CMAKE_RC_COMPILER</span></code>
        and <code class="computeroutput"><span class="identifier">CMAKE_MC_COMPILER</span></code> CMake
        options to the corresponding paths in the command line.
      </p>
</div>
<div class="copyright-footer">Copyright © 2007-2024 Andrey Semashev<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>).
      </p>
</div>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../installation.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../installation.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../design.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
